# 06 LlamaIndex入门

## 验证环境

```shell
uv venv -p 3.12
uv pip install llama-index
```

[LlamaIndex官方文档](https://developers.llamaindex.ai/python/framework/)


## 嵌入模型的部署方法

下面是为您整理好的 **Xinference** 与 **TEI (Text Embeddings Inference)** 部署 `BAAI/bge-m3` 的 Markdown 格式文档。您可以直接将其复制保存为 `.md` 文件使用。

---

### 1. Xinference 部署指南

Xinference 是一款功能强大的多模型管理平台。它不仅能部署大语言模型，还完美支持嵌入（Embedding）、重排（Reranker）以及图像、语音等多模态模型。

#### 步骤一：安装 Xinference

建议在干净的 Python 虚拟环境中安装（推荐 Python 3.10+）：

```bash
# 加上 [all] 会自动安装大部分常用的模型后端推理引擎
pip install "xinference[all]"

```

#### 步骤二：编写启动脚本

编写后台启动脚本 `start_xinference.sh`，用于在后台拉起 Xinference 本地服务：

```bash
cat << 'EOF' > start_xinference.sh
#!/bin/bash
# 启动 Xinference 核心守护服务，监听所有 IP 的 9997 端口
echo "Starting Xinference Supervisor & Worker..."
nohup xinference-local --host 0.0.0.0 --port 9997 > xinference.log 2>&1 &

# 等待 5 秒确保服务完全启动
sleep 5
echo "Xinference is running on port 9997."
EOF

```

#### 步骤三：运行并启动模型

1. 赋予脚本执行权限并启动：
```bash
chmod +x start_xinference.sh
./start_xinference.sh

```


2. 使用命令行一键拉取并部署 `bge-m3`：
```bash
xinference launch --model-name bge-m3 --model-type embedding

```


*服务会自动前往 Hugging Face（或 ModelScope 镜像源）下载 `BAAI/bge-m3` 的全量 PyTorch 权重并将其加载至显存中。*

#### 服务访问方式

* **OpenAI 兼容接口：** `http://<YOUR_IP>:9997/v1/embeddings`
* **Web 控制台：** 浏览器访问 `http://<YOUR_IP>:9997` 即可进入可视化管理后台。

```{warning}
xinference在通过pip install xinference[all]快捷安装，然后再部署bge-m3的过程的时候报错找不到包。安装了也报错，没有深入。
这个库引入的东西太多了，可能会出现位置错误。尽量还是使用TEI部署嵌入模型更加简单可靠。
```

---

### 2. TEI (Text Embeddings Inference) 部署指南

TEI 是 Hugging Face 官方采用 Rust 编写的高性能嵌入/重排服务器。它支持动态批处理（Dynamic Batching），在**生产环境中的吞吐量极高、延迟极低**。

#### 步骤一：准备环境

运行 TEI 强烈推荐使用官方 Docker 镜像，以避免在本地配置复杂的 Rust 与 CUDA 编译环境。请确保您的服务器已成功安装：

1. **Docker**
2. **NVIDIA Container Toolkit**（用于支持 Docker 调用 GPU）

### 步骤二：编写启动脚本

创建启动脚本 `start_tei.sh`。该脚本会拉起基于 GPU 的 TEI 容器，并将模型数据持久化在本地 `data` 目录下：

```bash
cat << 'EOF' > start_tei.sh
#!/bin/bash
# 1. 定义模型 ID 和本地模型权重缓存路径
MODEL_ID="BAAI/bge-m3"
VOLUME_PATH="$PWD/data"

# 创建缓存目录
mkdir -p $VOLUME_PATH

# 2. 通过 Docker 启动 TEI 容器 (使用 GPU 版本镜像)
echo "Starting HF Text Embeddings Inference (TEI) on Port 8080..."
docker run --gpus all \
  -p 8080:80 \
  -v $VOLUME_PATH:/data \
  --pull always \
  ghcr.io/huggingface/text-embeddings-inference:120-1.9 \
  --model-id $MODEL_ID \
  --max-client-batch-size 128 \
  --max-concurrent-requests 512
EOF
```


```{attention}
在下载的时候 https://github.com/huggingface/text-embeddings-inference 需要区分显卡的版本，根据不同的gpu版本选择对应的标签；

```

> **核心参数说明：**
> * `--gpus all`：映射宿主机所有 GPU。
> * `--max-client-batch-size`：单次客户端请求最大支持批量编码的文本数量。
> * `--max-concurrent-requests`：最大并发处理请求数，可根据显存和 CPU 核心数进行调整。
> 
> 

#### 步骤三：运行启动命令

1. 赋予脚本执行权限并后台运行：
```bash
chmod +x start_tei.sh
nohup ./start_tei.sh > tei_docker.log 2>&1 &

```


2. 观察容器日志以确保模型加载成功：
```bash
tail -f tei_docker.log

```



#### 服务访问方式

* **OpenAI 兼容接口：** `http://<YOUR_IP>:8080/v1/embeddings`
* **原生 API 接口：** `http://<YOUR_IP>:8080` (支持极速极简的原生 JSON 调用)

---

### 3. 部署方案对比快速选型

| 维度 | Xinference | TEI (Text Embeddings Inference) |
| --- | --- | --- |
| **适用场景** | 团队研发、一站式多模型托管、Mac/PC 本地测试 | 极高并发的生产环境、企业级 RAG 检索微服务 |
| **底层核心** | Python (支持 vLLM, llama.cpp 等后端) | Rust (专为 Embedding 和 Reranking 优化) |
| **接口规范** | 兼容 OpenAI / 包含专属 API | 兼容 OpenAI / 极速原生 API |
| **易用性** | 极高（带 Web 控制台和可视化资源监控） | 较高（纯 API/Docker 运行，无自带管理 UI） |